GnsClient Methods
The GnsClient object contains the following methods:
AcknowledgeNotification
The AcknowledgeNotification method sends an acknowledgment to a notification in either the Notification Queue or the Resend Queue.
Syntax
AcknowledgeNotification(AckId As Integer) As Boolean
Parameters
| Parameter | Required | Description |
|---|---|---|
|
AckId |
Yes |
The ID of the acknowledgment to be sent to a notification in one of the GNS queues. |
Example
The following example acknowledges the first entry in the Resend Queue:
Sub
Dim resendEntries
GnsClient.GetResendQueueEntries resendEntries
Dim ackIdToAck
ackIdToAck = 0
Dim idx
For idx = LBound(resendEntries) To UBound(resendEntries)
If ackIdToAck = 0 Then
ackIdToAck = resendEntries (idx, 3)
End If
Next
Dim bRet
bRet = False
If ackIdToAck <> 0 Then
bRet = GnsClient.AcknowledgeNotification ackIdToAck
End If
If (Not bRet) Then
MsgBox "Failed to acknowledge notification"
End if
End Sub
AcknowledgeNotifications
The AcknowledgeNotifications method sends multiple acknowledgments to multiple notifications in the Notification Queue or the Resend Queue.
Syntax
AcknowledgeNotifications(ArrayOfAckIds As Array, AcknowledgeResults As Array) As Array
Parameters
| Parameter | Required | Description |
|---|---|---|
|
ArrayOfAckIds |
Yes |
An array of IDs of acknowledgments to be sent to notifications in the GNS queues. |
| AcknowledgeResults | Yes | An array of Boolean values indicating whether the corresponding acknowledge succeeded. |
Remark
This method returns an array of Boolean values matched by index to the acknowledgment IDs in the method parameter.
Example
The following example acknowledges all of the entries in the Resend Queue:
Sub
Dim resendEntries
GnsClient.GetResendQueueEntries resendEntries
Dim arrayAckIdsToAck()
Dim arrayAckIdsToAckSize
arrayAckIdsToAckSize = 0
Dim idx
For idx = LBound(resendEntries) To UBound(resendEntries)
arrayAckIdsToAckSize = arrayAckIdsToAckSize + 1
ReDim Preserve arrayAckIdsToAck(arrayAckIdsToAckSize)
arrayAckIdsToAck (arrayAckIdsToAckSize - 1) = resendEntries (idx, 3)
Next
Dim arrayRet()
ReDim arrayRet(arrayAckIdsToAckSize)
If arrayAckIdsToAckSize <> 0 Then
GnsClient.AcknowledgeNotifications arrayAckIdsToAck, arrayRet
For idx = 0 To arrayAckIdsToAckSize - 1
If (Not arrayRet(idx)) Then
MsgBox "Failed to acknowledge notification for Ack ID " + arrayAckIdsToAck(idx)
End if
Next
End If
End Sub
AddRecordXmlArrayAttribute
The AddRecordXmlArrayAttribute method adds the given value to the end of the array in the given XML string. The "dates" field for the Blackout record is the only current array-type property in CxGns.
Syntax
AddRecordXmlArrayAttribute(Attr As String, Value As String, RecXML As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
Attr |
Yes |
The attribute to be retrieved. |
|
Value |
Yes |
The value to add to the array. |
|
RecXML |
Yes |
The XML representation of a blackout record. |
Remark
Note that this method only modifies an XML string; it does not modify the actual record.
Example
The following example adds the date "09/23/2023" to the "dates" array of the XML representation of blackout record 0000000008:
Sub
Dim strRecord
strRecord = GnsClient.GetBlackoutRecord("0000000008")
Dim strXml
strXml = GnsClient.AddRecordXmlArrayAttribute("dates", "20230923", strRecord)
MsgBox strXml
End Sub
Connect
The Connect method connects the object to a service.
Syntax
Connect(DomainSiteService As String)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DomainSiteService |
Yes |
The [Domain]Site.Service to which to connect. The domain is optional. The service must be a valid one. |
Remarks
Returns 0 if successful and a non-zero value if the connection failed.
Example
The following example connects the Client object to the CYGDEMO.<SVC> on domain 5410:
Connect
Sub GnsConnect()
'Connect to a GNS
Dim GnsClient
Set GnsClient = CreateObject("CxGns.GnsClient")
GnsClient.Connect("[5410]CYGDEMO.GNS")
End Sub
CreateAddressRecord
The CreateAddressRecord method creates a new address record and assigns it to the given GNS ID.
Syntax
CreateAddressRecord(GnsID As String, NewRecXML As String) As Boolean
Parameters
| Parameter | Required | Description |
|---|---|---|
|
GnsID |
Yes |
The GNS ID for the record that will have the new address record. |
|
NewRecXML |
Yes |
The new data for the record. |
Remark
The following is an example of a GNS address record in XML:
<CygNetGnsAddressRecord lock_user="VSI\" lock_time="-1284766309" key="0000000005A0000001" type="SM" address="my.email@mydomain.com" address_desc="My email address" numeric_display="0" rtn_flag="1" ack_flag="0" retries="0" retry_delay="0" next_to_notify="" resend_flag="1" resend_time="5" blkout_mode="D" retry_rules_forwarded="0" ignore_prev_retry_rules="0"/>Example
The following example creates a new address record in GNS record "MYRECORD":
CreateAddressRecord
Sub
' Creates the following XML
' <CygNetGnsAddressRecord type="SM" address="my.email@mydomain.com"/>
Dim strRecXml
strRecXml = GnsClient.GetEmptyRecordXml("ADDRESS")
strRecXml = GnsClient.SetRecordXmlAttribute("type", "SM", "ADDRESS", strRecXml)
strRecXml = GnsClient.SetRecordXmlAttribute("address", "my.email@mydomain.com", "ADDRESS", strRecXml)
Dim bRet
bRet = GnsClient.CreateAddressRecord("MYRECORD", strRecXml)
If (Not bRet) Then
MsgBox "Failed to create address record"
End if
End Sub
CreateBlackoutRecord
The CreateBlackoutRecord method creates a new blackout record and assigns it to the given address.
Syntax
CreateBlackoutRecord(AddrKey As String, NewRecXML As String) As Boolean
Parameters
| Parameter | Required | Description |
|---|---|---|
|
AddrKey |
Yes |
The database key (DbKey) for the address record, which is obtained via GetAddressRecords. |
|
NewRecXML |
Yes |
The new data for the record. |
Remark
The following is an example of a GNS blackout record in XML:
<CygNetGnsBlackoutRecord key="0000000008" name="MyBlackoutRecord" description="My blackout record" active="1" type="D" start_time="070000" end_time="110000" is_sel_sunday="1" is_sel_monday="0" is_sel_tuesday="0" is_sel_wednesday="0" is_sel_thursday="0" is_sel_friday="0" is_sel_saturday="0"/>Example
The following example creates a new blackout record for address record with database key 0000000009A0000001:
Sub
Dim strRecXml
strRecXml = GnsClient.GetEmptyRecordXml("BLACKOUT")
strRecXml = GnsClient.SetRecordXmlAttribute("name", "MyBlackoutRecord", "BLACKOUT", strRecXml)
strRecXml = GnsClient.SetRecordXmlAttribute("is_sel_sunday", "1", "BLACKOUT", strRecXml)
strRecXml = GnsClient.SetRecordXmlAttribute("type", "D", "BLACKOUT", strRecXml)
Dim bRet
bRet = GnsClient.CreateBlackoutRecord("0000000009A0000001", strRecXml)
If (Not bRet) Then
MsgBox "Failed to create blackout record"
End if
End Sub
CreateBroadcast
The CreateBroadcast method creates a new broadcast record with the provided message and datetime range. See CygNet Broadcast for more information. Also see DeleteAllBroadcasts.
Syntax
CreateBroadcast(ByVal strMessage As String, ByVal dtStartDateTime As Date, ByVal dtEndDateTime As Date) As Integer
Parameters
| Parameter | Required | Description |
|---|---|---|
|
strMessage |
Yes |
Specifies the message to be broadcast. |
|
dtStartDateTime |
Yes |
Specifies the start date and time for a date range. |
|
dtEndDateTime |
Yes |
Specifies the end date and time for a date range. Once the end date has passed, the broadcast will disappear. |
Example
The following example could be used on a button to create a CygNet broadcast message.
Sub btnCreate_EventClick()
Dim This : Set This = btnCreate
If strSiteService <> "" Then
Dim gnsClient
Set gnsClient = CreateObject("CxGns.GnsClient")
gnsClient.Connect(strSiteService)
Dim id, strMessage, dtStart, dtEnd
strMessage = "Donuts in the breakroom!!!"
dtStart = "06/06/2023 00:00"
dtEnd = "06/07/2023 00:00"
id = gnsClient.CreateBroadcast(strMessage, dtStart, dtEnd)
If id <> 0 Then
MsgBox "Broadcast successfully committed (ID# : " & id & ")"
Else
MsgBox "There was an error submitting your broadcast (" & id & "). Make sure your GNS configured To send broadcasts."
End If
End If
End Sub
CreateGnsHeaderRecord
The CreateGnsHeaderRecord method creates a new GNS entry record with the given GNS ID with the given data.
Syntax
CreateGnsHeaderRecord(NewRecXML As String) As Boolean
Parameters
| Parameter | Required | Description |
|---|---|---|
|
NewRecXML |
Yes |
The new data for the record. |
Remark
The following is an example of a GNS header record in XML:
<CygNetGnsHeaderRecord gns_id="GNSID1" gns_id_type="event" category="Notification Item" description="Test GNS ID" wav_filename="" rtn_wav_filename="" numeric_msg="1" rtn_numeric_msg="1" subject="Test GNS Set Message" rtn_subject="Test GNS Clear Message" />Example
The following example creates a new GNS header record.
Sub
' Creates the following XML
' < CygNetGnsHeaderRecord gns_id="NEWRECORD" gns_id_type ="event"/>
Dim strRecXml
strRecXml = GnsClient.GetEmptyRecordXml("HEADER")
strRecXml = GnsClient.SetRecordXmlAttribute("gns_id", "NEWRECORD", "HEADER", strRecXml)
strRecXml = GnsClient.SetRecordXmlAttribute("gns_id_type", "event", "HEADER", strRecXml)
Dim bRet
bRet = GnsClient.CreateGnsHeaderRecord(strRecXml)
If (Not bRet) Then
MsgBox "Failed to create GNS header record"
End if
End Sub
DeleteAddressRecord
The DeleteAddressRecord method deletes the address record.
Syntax
DeleteAddressRecord(DbKey As String) As Boolean
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DbKey |
Yes |
The database key (DbKey) for the address record, which is obtained via GetAddressRecords. |
Example
The following example deletes an address record with database key 0000000004A0000002:
Sub
Dim bRet
bRet = GnsClient.DeleteAddressRecord("0000000004A0000002")
If (Not bRet) Then
MsgBox "Failed to delete address record"
End If
End Sub
DeleteAllBroadcasts
The DeleteAllBroadcasts method deletes all broadcast records. See CygNet Broadcast for more information. Also see CreateBroadcasts.
Syntax
DeleteAllBroadcasts
Example
The following example could be used on a button to delete all CygNet broadcast messages:
Sub btnPurge_EventClick()
Dim This : Set This = btnPurge
Dim gnsClient
Set gnsClient = CreateObject("CxGns.GnsClient")
gnsClient.Connect(strSiteService)
gnsClient.DeleteAllBroadcasts
End Sub
DeleteGnsHeaderRecord
The DeleteGnsHeaderRecord method deletes the GNS entry with the given ID.
Syntax
DeleteGnsHeaderRecord(GnsID As String) As Boolean
Parameters
| Parameter | Required | Description |
|---|---|---|
|
GnsID |
Yes |
The GNS ID for the record. |
Example
The following example deletes a GNS header record with ID "OLDRECORD":
Sub
Dim bRet
bRet = GnsClient.DeleteGnsHeaderRecord("OLDRECORD")
If (Not bRet) Then
MsgBox "Failed to delete GNS header record"
End if
End Sub
DeleteNotification
The DeleteNotification method deletes a notification from the Notification Queue.
Syntax
DeleteNotification(NotifID As Integer) As Boolean
Parameters
| Parameter | Required | Description |
|---|---|---|
|
NotifID |
Yes |
The ID of the notification. |
Remark
Note that this method is only used for deleting a notification in the Notification Queue. To delete a notification from the Resend Queue, use DeleteResendNotification.
Example
The following example deletes all the notifications in the Notification Queue:
Sub
Dim notifEntries
GnsClient.GetNotificationQueueEntries notifEntries
Dim idx
For idx = LBound(notifEntries) To UBound(notifEntries)
If (Not GnsClient.DeleteNotification(notifEntries (idx, 4))) Then
MsgBox "Failed to delete notification " + notifEntries (idx, 4)
End if
Next
End Sub
DeleteResendNotification
The DeleteResendNotification method deletes a notification from the Resend Queue.
Syntax
DeleteResendNotification(NotifID As Integer) As Boolean
Parameters
| Parameter | Required | Description |
|---|---|---|
|
NotifID |
Yes |
The ID of the notification. |
Remark
Note that this method is only used for deleting a notification in the Resend Queue. To delete a notification from the Resend Queue, use DeleteNotification.
Example
The following example deletes all notifications in the Resend Queue:
Sub
Dim resendEntries
GnsClient.GetResendQueueEntries resendEntries
Dim idx
For idx = LBound(resendEntries) To UBound(resendEntries)
If (Not GnsClient.DeleteResendNotification(resendEntries(idx, 4))) Then
MsgBox "Failed to delete resend notification " + resendEntries(idx, 4)
End if
Next
End Sub
Disconnect
The Disconnect method disconnects from the connected service.
Syntax
Disconnect() As Integer
Remarks
The Disconnect method returns 0 if successful and a non-zero value if the disconnect failed.
Example
The following example disconnects the Client object from the connected service, and pops a message box if it is unsuccessful:
Sub Svc.Disconnect()
<SvcClient>.Disconnect()
MsgBox "Service has disconnected."
If <SvcClient>.Disconnect <> 0
Then
MsgBox "Failed to disconnect."
End If
End Sub
GetAddressRecord
The GetAddressRecord method returns the data for the address record with the given DB key.
Syntax
GetAddressRecord(DbKey As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DbKey |
Yes |
The database key (DbKey) for the address record, which is obtained via GetAddressRecords. |
Example
The following example gets the address record for database key 0000000002A0000003:
Sub
Dim strRecord
strRecord = GnsClient.GetAddressRecord("0000000002A0000003")
MsgBox strRecord
End Sub
GetAddressRecords
The GetAddressRecords method returns the data for all address records for the given GNS ID, including the records’ database keys for referencing them later.
Syntax
GetAddressRecords(GnsID As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
GnsID |
Yes |
The GNS ID for the record. |
Example
The following example gets all address records for GNS record "MYRECORD":
Sub
Dim strRecords
strRecords = GnsClient.GetAddressRecords("MYRECORD")
MsgBox strRecords
End Sub
GetBlackoutRecord
The GetBlackoutRecord method returns the data for the blackout record with the given database key.
Syntax
GetBlackoutRecord(DbKey As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DbKey |
Yes |
The database key (DbKey) for the blackout record, which is obtained via GetBlackoutRecords. |
Example
The following example gets the blackout record for database key 0000000007:
Sub
Dim strRecord
strRecord = GnsClient.GetBlackoutRecord("0000000007")
MsgBox strRecord
End Sub
GetBlackoutRecords
The GetBlackoutRecords method returns the data for all blackout records for the given address database key, including the records’ GNS DB keys for referencing them later.
Syntax
GetBlackoutRecords(AddrDbKey As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
AddrDbKey |
Yes |
The database key (DbKey) (AddrDbKey) for the address record, which is obtained via GetAddressRecords. |
Example
The following example gets all blackout records for address database key 0000000002A0000003:
Sub
Dim strRecord
strRecord = GnsClient.GetBlackoutRecords("0000000002A0000003")
MsgBox strRecord
End Sub
GetConsoleData
The GetConsoleData method returns the console text and display attributes as two 25x80 arrays of unsigned characters.
Syntax
GetConsoleData(ByRef pText, ByRef pAttr) As Integer
Parameters
| Parameter | Required | Description |
|---|---|---|
|
pText |
Yes |
A two-dimensional 25x80 array of console text attributes returned by this method. |
|
pAttr |
Yes |
A two-dimensional 25x80 array of console display attributes returned by this method. |
Remarks
This method returns 0 if successful.
Example
The following example writes the console text and display attributes to a CSV file.
Sub
Dim aryText, aryAttr, nRet
nRet = <NameofServiceClientObject>.GetConsoleData(aryText, aryAttr)
' Write text attributes to CSV file
Dim i, j, strMsg
For i = 0 To UBound(aryText, 1)
For j = 0 To UBound(aryText, 2)
strMsg = strMsg + CStr(aryText(i, j)) + ","
Next
strMsg = strMsg + vbCr
Next
dim fso, file
Set fso = CreateObject("Scripting.FileSystemObject")
Set file = fso.OpenTextFile("c:\console_text_attrs.csv", 2, True)
file.WriteLine(strMsg)
file.Close
strMsg = ""
' Write display attributes to CSV file
For i = 0 To UBound(aryAttr, 1)
For j = 0 To UBound(aryAttr, 2)
strMsg = strMsg + CStr(aryAttr(i, j)) + ","
Next
strMsg = strMsg + vbCr
Next
Set file = fso.OpenTextFile("c:\console_disp_attrs.csv", 2, True)
file.WriteLine(strMsg)
file.Close
MsgBox nRet
End Sub
GetEmptyRecordXml
The GetEmptyRecordXml method returns an XML string representation of a blank record.
Syntax
GetEmptyRecordXml(RecType As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
RecType |
Yes |
The type of record represented by RecXML, including:
|
Remark
This method can be used in the process of creating a new record. After the empty record XML is retrieved, use the SetRecordXMLAttribute method to set the new GNS record attribute values. Then use the CreateGnsHeaderRecord, CreateAddressRecord, or CreateBlackoutRecord methods to add the new record from the XML string created by the SetRecordXMLAttribute method.
The string is returned as XML.
Example
The following example creates an address record from an empty address record XML:
Sub
' Creates the following XML
' <CygNetGnsAddressRecord type="SM" address="my.email@mydomain.com"/>
Dim strRecXml
strRecXml = GnsClient.GetEmptyRecordXml("ADDRESS")
strRecXml = GnsClient.SetRecordXmlAttribute("type", "SM", "ADDRESS", strRecXml)
strRecXml = GnsClient.SetRecordXmlAttribute("address", "my.email@mydomain.com", "ADDRESS", strRecXml)
Dim bRet
bRet = GnsClient.CreateAddressRecord("MYRECORD", strRecXml)
If (Not bRet) Then
MsgBox "Failed to create address record"
End if
End Sub
GetGnsHeaderRecord
The GetGnsHeaderRecord method returns the information from the header record for the given GNS ID.
Syntax
GetGnsHeaderRecord(GnsID As String, ForUpdate As Boolean) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
GnsID |
Yes |
The GNS ID for the record. |
|
ForUpdate |
No |
Indicates whether or not to lock the record for updating. |
Example
The following example gets the GNS header record with ID "MYRECORD":
Sub
Dim strRecord
strRecord = GnsClient.GetGnsHeaderRecord("MYRECORD", false)
MsgBox strRecord
End Sub
GetGnsHeaderRecordsByFilter
The GetGnsHeaderRecordsByFilter method returns the information from the header record for the given GNS ID filtered by status.
Syntax
GetGnsHeaderRecordsByFilter(StatusFilter As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
StatusFilter |
Yes |
The filter of record status to display, including:
|
Example
The following example gets all GNS header records filtered by the ACTIVE status.
Sub
Dim strRecords
strRecords = GnsClient.GetGnsHeaderRecordsByFilter("ACTIVE")
MsgBox strRecords
End Sub
GetMessageRecord
The GetMessageRecord method returns the information from the message record for the given GNS ID.
Syntax
GetMessageRecord(GnsID As String, Type As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
GnsID |
Yes |
The GNS ID for the record whose Set message record will be returned. |
|
Type |
Yes |
The type of message record to be retrieved, including:
|
Example
The following example gets SET message records for GNS record with ID "MYEVENTRECORD":
Sub
Dim strRecord
strRecord = GnsClient.GetMessageRecord("MYEVENTRECORD", "SET")
MsgBox strRecord
End Sub
GetNotificationQueueEntries
The GetNotificationQueueEntries method returns the array of entries in the Notification Queue.
Syntax
GetNotificationQueueEntries(NotificationQueueContents As Array)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
NotificationQueueContents |
Yes |
The two-dimensional array of Notification Queue entries returned by this method. |
Remark
This method returns a two-dimensional array of all of the entries in the Notification Queue. The columns of this array are as follows:
| Column | Description |
|---|---|
| 0 | Starting notification |
| 1 | GNS ID |
| 2 | Address |
| 3 | Ack ID |
| 4 | Notif ID |
| 5 | Status |
| 6 | Site.Service |
| 7 | Long ID |
| 8 | Facility ID |
| 9 | UDC |
Note that this method only returns entries in the Notification Queue. To retrieve entries in the Resend Queue, use GetResendQueueEntries.
Example
The following example gets the array of entries in the Notification Queue, and then acknowledges the first one:
Sub
Dim notifEntries
GnsClient.GetNotificationQueueEntries notifEntries
Dim ackIdToAck
ackIdToAck = 0
Dim idx
For idx = LBound(notifEntries) To UBound(notifEntries)
If ackIdToAck = 0 Then
ackIdToAck = notifEntries (idx, 3)
End If
Next
Dim bRet
bRet = False
If ackIdToAck <> 0 Then
bRet = GnsClient.AcknowledgeNotification(ackIdToAck)
End If
If (Not bRet) Then
MsgBox "Failed to acknowledge notification"
End if
End Sub
GetNotificationQueueEntriesForAddress
The GetNotificationQueueEntriesForAddress method returns the array of entries in the Notification Queue for a specified address.
Syntax
GetNotificationQueueEntriesForAddress(Address As String, NotificationQueueContents As Array)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
Address |
Yes |
The address for which to retrieve Notification Queue entries. Note that this is the address itself, not the database key for the address record. |
|
NotificationQueueContents |
Yes |
The two-dimensional array of Notification Queue entries returned by this method |
Remark
This method returns a two-dimensional array of all of the entries in the Notification Queue. The columns of this array are as follows:
| Column | Description |
|---|---|
| 0 | Starting notification |
| 1 | GNS ID |
| 2 | Address |
| 3 | Ack ID |
| 4 | Notif ID |
| 5 | Status |
| 6 | Site.Service |
| 7 | Long ID |
| 8 | Facility ID |
| 9 | UDC |
Note that this method only returns entries in the Notification Queue. To retrieve entries in the Resend Queue, use GetResendQueueEntriesForAddress.
Example
The following example gets the array of entries in the Notification Queue for an address, and then acknowledges the first one:
Sub
Dim notifEntries
GnsClient.GetNotificationQueueEntriesForAddress"my.email@mydomain.com" notifEntries
Dim ackIdToAck
ackIdToAck = 0
Dim idx
For idx = LBound(notifEntries) To UBound(notifEntries)
If ackIdToAck = 0 Then
ackIdToAck = notifEntries (idx, 3)
End If
Next
Dim bRet
bRet = False
If ackIdToAck <> 0 Then
bRet = GnsClient.AcknowledgeNotification(ackIdToAck)
End If
If (Not bRet) Then
MsgBox "Failed to acknowledge notification"
End if
End Sub
GetRecordXml
The GetRecordXml method returns the XML for the record from the given XML string.
Syntax
GetRecordXml(UID As String, RecType As String, RecsXML As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
UID |
Yes |
The unique identifier of the record, which differs for each type of record:
|
|
RecType |
Yes |
The type of records represented by RecsXML, including:
|
|
RecsXML |
Yes |
The XML representation of multiple records. |
Example
The following example gets the XML for the address record 0000000009A0000001 of GNS record "MYRECORD":
Sub
Dim strRecords
strRecords = GnsClient.GetAddressRecords("MYRECORD")
Dim strXml
strXml = GnsClient.GetRecordXml("0000000009A0000001", "ADDRESS", strRecords)
MsgBox strXml
End Sub
GetRecordXmlArrayAttribute
The GetRecordXmlArrayAttribute method returns the value from the given XML string of the given array-type property. The "dates" field for the Blackout record is the only current array-type property in CxGns.
Syntax
GetRecordXmlArrayAttribute(Attr As String, Index as Int, RecXML As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
Attr |
Yes |
The attribute to be retrieved. |
|
Index |
Yes |
The index into the array for the desired value. |
|
RecXML |
Yes |
The XML representation of a blackout record. |
Example
The following example gets the first date in the "dates" array of the XML representation of blackout record 0000000008:
Sub
Dim strRecord
strRecord = GnsClient.GetBlackoutRecord("0000000008")
Dim strDate
strDate = GnsClient.GetRecordXmlArrayAttribute("dates", 0, strRecord)
MsgBox strDate
End Sub
GetRecordXmlAttribute
The GetRecordXmlAttribute method returns the value from the given XML string of the given property.
Syntax
GetRecordXmlAttribute(Attr As String, RecType As String, RecXML As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
Attr |
Yes |
The attribute to be retrieved. |
|
RecType |
Yes |
The type of record represented by RecXML, including:
|
|
RecXML |
Yes |
The XML representation of a record. |
Remark
The attribute being searched for must be in the RecXML. If the attribute is not included, this method will return an empty string.
Example
The following example gets the "address" attribute from the address record with database key 0000000009A0000001:
Sub
Dim strRecord
strRecord = GnsClient.GetAddressRecord("0000000009A0000001")
Dim strAttribute
strAttribute = GnsClient.GetRecordXmlAttribute("address", "ADDRESS", strRecord)
MsgBox strAttribute
End Sub
GetReferences
The GetReferences method refreshes the list of services referenced by the connected service.
Syntax
GetReferences() As Integer
Return Values
This method returns all references for the connected service.
Example
The following example refreshes the connected services:
Sub GetReferences()
<NameofServiceClientObject>.GetReferences
MsgBox "Services references retrieved"
End Sub
GetResendQueueEntries
The GetResendQueueEntries method returns the array of entries in the Resend Queue.
Syntax
GetResendQueueEntries(ResendQueueContents As Array)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
ResendQueueContents |
Yes |
The two-dimensional array of Resend Queue entries returned by this method. |
Remark
This method returns a two-dimensional array of all of the entries in the Resend Queue. The columns of this array are as follows:
| Column | Description |
|---|---|
| 0 | Starting notification |
| 1 | GNS ID |
| 2 | Address |
| 3 | Ack ID |
| 4 | Resend ID |
| 5 | Status |
| 6 | Site.Service |
| 7 | Long ID |
| 8 | Facility ID |
| 9 | UDC |
Note that this method only returns entries in the Resend Queue. To retrieve entries in the Notification Queue, use GetNotificationQueueEntries.
Example
The following example gets the array of entries in the Resend Queue, and then acknowledges the first one:
Sub
Dim resendEntries
GnsClient.GetResendQueueEntries resendEntries
Dim ackIdToAck
ackIdToAck = 0
Dim idx
For idx = LBound(resendEntries) To UBound(resendEntries)
If ackIdToAck = 0 Then
ackIdToAck = resendEntries (idx, 3)
End If
Next
Dim bRet
bRet = False
If ackIdToAck <> 0 Then
bRet = GnsClient.AcknowledgeNotification(ackIdToAck)
End If
If (Not bRet) Then
MsgBox "Failed to acknowledge notification"
End if
End Sub
GetResendQueueEntriesForAddress
The GetResendQueueEntriesForAddress method returns the array of entries in the Resend Queue for a specified address.
Syntax
GetResendQueueEntriesForAddress(Address As String, ResendQueueContents As Array)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
Address |
Yes |
The address for which to retrieve Resend Queue entries. Note that this is the address itself, not the database key for the address record. |
|
ResendQueueContents |
Yes |
The two-dimensional array of Resend Queue entries returned by this method. |
Remark
This method returns a two-dimensional array of all of the entries in the Resend Queue. The columns of this array are as follows:
| Column | Description |
|---|---|
| 0 | Starting notification |
| 1 | GNS ID |
| 2 | Address |
| 3 | Ack ID |
| 4 | Resend ID |
| 5 | Status |
| 6 | Site.Service |
| 7 | Long ID |
| 8 | Facility ID |
| 9 | UDC |
Note that this method only returns entries in the Resend Queue. To retrieve entries in the Notification Queue, use GetNotificationQueueEntriesForAddress.
Example
The following example gets the array of entries in the Resend Queue for an address, and then acknowledges the first one:
Sub
Dim resendEntries
GnsClient.GetResendQueueEntriesForAddress "my.email@mydomain.com" resendEntries
Dim ackIdToAck
ackIdToAck = 0
Dim idx
For idx = LBound(resendEntries) To UBound(resendEntries)
If ackIdToAck = 0 Then
ackIdToAck = resendEntries (idx, 3)
End If
Next
Dim bRet
bRet = False
If ackIdToAck <> 0 Then
bRet = GnsClient.AcknowledgeNotification(ackIdToAck)
End If
If (Not bRet) Then
MsgBox "Failed to acknowledge notification"
End if
End Sub
GetUniqueIDs
The GetUniqueIDs method returns the unique identifiers for all records from the given XML string.
Syntax
GetUniqueIDs(RecType As String, RecsXML As String, UniqueIds As Array)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
RecType |
Yes |
The type of records represented by RecsXML, including:
|
|
RecsXML |
Yes |
The XML representation of multiple records. |
|
UniqueIds |
Yes |
The list of unique IDs returned by this method |
Example
The following example gets the unique identifiers for the address records of GNS header "MYRECORD":
Sub
Dim strRecords
strRecords = GnsClient.GetAddressRecords("MYRECORD")
Dim aryIds
GnsClient.GetUniqueIDs "ADDRESS", strRecords, aryIds
Dim i
For i = 0 To UBound(aryIds)
MsgBox aryIds(0)
Next
End Sub
RemoveRecordXmlArrayAttribute
The RemoveRecordXmlArrayAttribute method removes the value at the given index from the array in the given XML string. The "dates" field for the Blackout record is the only current array-type property in CxGns.
Syntax
RemoveRecordXmlArrayAttribute(Attr As String, Index as Int, RecXML As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
Attr |
Yes |
The attribute to be retrieved. |
|
Index |
Yes |
The index into the array for the desired value. |
|
RecXML |
Yes |
The XML representation of a blackout record. |
Remark
Note that this method only modifies an XML string; it does not modify the actual record.
Example
The following example removes the date at the first index of the "dates" array in the XML representation of blackout record 0000000008:
Sub
Dim strRecord
strRecord = GnsClient.GetBlackoutRecord("0000000008")
Dim strXml
strXml = GnsClient.RemoveRecordXmlArrayAttribute("dates", 0, strRecord)
MsgBox strXml
End Sub
SendTestNotification
The SendTestNotification method sends a test notification message from the given GNS ID.
Syntax
SendTestNotification(GnsID As String)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
GnsID |
Yes |
The GNS ID for the record from which to send a test message. |
Example
The following example sends a test notification from the GNS record with ID "MYRECORD":
SetRecordXml
The SetRecordXml method sets the XML for the record from the given XML string.
Syntax
SetRecordXml(UID As String, RecType As String, NewRecXML As String, RecsXML As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
UID |
Yes |
The unique identifier of the record, which differs for each type of record:
|
|
RecType |
Yes |
The type of records represented by RecsXML, including:
|
|
NewRecXML |
Yes |
The new data for the record. |
|
RecsXML |
Yes |
The XML representation of multiple records. |
Remark
Note that this method only modifies an XML string; it does not modify the actual record.
Example
The following example copies all of the data from the address record with database key 0000000009A0000001 into the XML representation of the address record with database key 0000000009A0000002:
Sub
Dim strRecords
strRecords = GnsClient.GetAddressRecords("MYRECORD")
Dim strRecordToCopy
strRecordToCopy = GnsClient.GetAddressRecord("0000000009A0000001")
strRecordToCopy = GnsClient.SetRecordXmlAttribute("key", "0000000009A0000002", "ADDRESS", strRecordToCopy)
Dim strXml
strXml = GnsClient.SetRecordXml("0000000009A0000002", "ADDRESS", strRecordToCopy, strRecords)
MsgBox strXml
End Sub
SetRecordXmlArrayAttribute
The SetRecordXmlArrayAttribute method sets the value from the given XML string of the given array-type property. The "dates" field for the Blackout record is the only current array-type property in CxGns.
Syntax
SetRecordXmlArrayAttribute(Attr As String, Index as Int, Value As String, RecXML As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
Attr |
Yes |
The attribute to be retrieved. |
|
Index |
Yes |
The index into the array for the desired value. |
|
Value |
Yes |
The value to which the attribute is to be set. |
|
RecXML |
Yes |
The XML representation of a blackout record. |
Remark
Note that this method only modifies an XML string; it does not modify the actual record.
Example
The following example sets the date at the first index of the "dates" array to "09/01/2023" in the XML representation of blackout record 0000000008:
Sub
Dim strRecord
strRecord = GnsClient.GetBlackoutRecord("0000000008")
Dim strXml
strXml = GnsClient.SetRecordXmlArrayAttribute("dates", 0, "20230901", strRecord)
MsgBox strXml
End Sub
SetRecordXmlAttribute
The SetRecordXmlAttribute method sets the value of the given property in the given XML string.
Syntax
SetRecordXmlAttribute(Attr As String, Value As String, RecType As String, RecXML As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
Attr |
Yes |
The attribute to be set. |
|
Value |
Yes |
The value to which the attribute is to be set. |
|
RecType |
Yes |
The type of record represented by RecXML, including:
|
|
RecXML |
Yes |
The XML representation of a record. Generated by GetXMLRecord. |
Remark
This method returns the XML with the specified attribute’s value replaced by the given value. Note that this method only modifies an XML string; it does not modify the actual record.
Example
The following example gets an address record, updates the "address" attribute, and then updates the address record with the resulting XML:
Sub
Dim strRecord
strRecord = GnsClient.GetAddressRecord("0000000009A0000001")
Dim strXml
strXml = GnsClient.SetRecordXmlAttribute("address", "my.new.email@mydomain.com", "ADDRESS", strRecord)
Dim bRet
bRet = GnsClient.UpdateAddressRecord("0000000009A0000001", strXml)
If (Not bRet) Then
MsgBox "Failed to update address record"
End if
End Sub
UpdateAddressRecord
The UpdateAddressRecord method updates the record that corresponds to the DB key with the given data.
Syntax
UpdateAddressRecord(DbKey As String, NewRecXML As String) As Boolean
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DbKey |
Yes |
The database key (DbKey) for the address record, which is obtained via GetAddressRecords. |
|
NewRecXML |
Yes |
The new data for the record. |
Example
The following example updates the address record with database key 0000000009A0000001:
Sub
Dim strRecord
strRecord = GnsClient.GetAddressRecord("0000000009A0000001")
Dim strXml
strXml = GnsClient.SetRecordXmlAttribute("address", "my.new.email@mydomain.com", "ADDRESS", strRecord)
Dim bRet
bRet = GnsClient.UpdateAddressRecord("0000000009A0000001", strXml)
If (Not bRet) Then
MsgBox "Failed to update address record"
End if
End Sub
UpdateBlackoutRecord
The UpdateBlackoutRecord method updates the record that corresponds to the DB key with the given data.
Syntax
UpdateBlackoutRecord(DbKey As String, NewRecXML As String) As Boolean
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DbKey |
Yes |
The database key (DbKey) for the blackout record, which is obtained via GetBlackoutRecords. |
|
NewRecXML |
Yes |
The new data for the record. |
Example
The following example updates a blackout record with database key 0000000008:
Sub
Dim strRecord
strRecord = GnsClient.GetBlackoutRecord("0000000008")
Dim strXml
strXml = GnsClient.SetRecordXmlAttribute("name", "NewName", "BLACKOUT", strRecord)
Dim bRet
bRet = GnsClient.UpdateBlackoutRecord("0000000008", strXml)
If (Not bRet) Then
MsgBox "Failed to update Blackout record"
End if
End Sub
UpdateGnsHeaderRecord
The UpdateGnsHeaderRecord method updates the GNS entry for the given GNS ID with the given data.
Syntax
UpdateGnsHeaderRecord(GnsID As String, NewRecXML As String) As Boolean
Parameters
| Parameter | Required | Description |
|---|---|---|
|
GnsID |
Yes |
The GNS ID for the record official. |
|
NewRecXML |
Yes |
The new data for the record. |
Example
The following example updates a GNS header record with ID "MYRECORD":
Sub
Dim strRecord
strRecord = GnsClient.GetGnsHeaderRecord("MYRECORD", true)
Dim strXml
strXml = GnsClient.SetRecordXmlAttribute("description", "New description", "HEADER", strRecord)
Dim bRet
bRet = GnsClient.UpdateGnsHeaderRecord("MYRECORD", strXml)
If (Not bRet) Then
MsgBox "Failed to update GNS header record"
End if
End Sub
UpdateMessageRecord
The UpdateMessageRecord method updates the GNS entry for the given GNS ID with the given message data.
Syntax
UpdateMessageRecord(GnsID As String, Type As String, NewRecXML As String) As Boolean
Parameters
| Parameter | Required | Description |
|---|---|---|
|
GnsID |
Yes |
The GNS ID for the record. |
|
Type |
Yes |
The type of message record to be retrieved, including:
|
|
NewRecXML |
Yes |
The new data for the Set message record. |
Example
The following example updates the message record for GNS header record with ID "MYRECORD":
Sub
Dim strRecord
strRecord = GnsClient.GetMessageRecord("MYRECORD", "SET")
Dim strXml
strXml = GnsClient.SetRecordXmlAttribute("message", "New message", "MESSAGE", strRecord)
Dim bRet
bRet = GnsClient.UpdateMessageRecord("MYRECORD", "SET", strXml)
If (Not bRet) Then
MsgBox "Failed to update message record"
End if
End Sub
